reservations-eapi

The Basic Usage page introduced the concept of a bundle. A bundle is used by the reservation service to determine the best availability for one or more products. With the Basic Usage example a simple single product, single passenger bundle was provided, which means that the response provided availability just for that product, with no consideration or influence of other products or number of passengers travelling. This is a very simplistic question and response, providing the most basic information regarding availability. This type of query is useful if a single passenger is travelling and it is already known what product they wish to make a booking with. A good example of this may be a season ticket holder, who already holds a ticket and is looking to book a seat as part of their regular commute.

However, bundles can be expanded in multiple ways to allow the reservation service to provide much more useful information, either in terms of which products are available or in cases of multiple passengers travelling together - or of course any combination of the two. This page outlines some examples of how bundles can be constructed to provide the best and most accurate availability response for different combinations of products and passengers.

NOTE: The below isn't exhaustive, there are other examples which may be of relevance to different retailers depending on how their sales pipeline is set up. This page is intended to give an introduction to the most common usage patterns and consumers can engage with RDG on other patterns or combinations which they may wish to better understand.

Single Passenger Requests

Restating the most basic type of bundle, as seen in the Basic Usage example:

"bundles": [{"id": "bundle_1","products": [{"ticketTypeCode": "SVS", "routeCode": "00000"}]}]

In this request, a single bundle is requested for SVS, 00000 and will apply to all passengers, The Basic Usage bundle checks for the availability of a single product. However, in many cases it is not known prior to the availability check which product a Customer will ultimately go on to buy so a common availability request will be searching for availability over multiple products. The availability search enables this type of request in a number of different ways.

Mono Product Bundles

A mono product bundle is the simplest extension of the Basic Usage example. This search pattern allows users to check for the availability of multiple products in one request, each in isolation from each other:

"bundles": [
    {"id": "bundle_1","products": [{"ticketTypeCode": "SVS", "routeCode": "00000"}]},
    {"id": "bundle_2","products": [{"ticketTypeCode": "SDS", "routeCode": "00000"}]},
    {"id": "bundle_3","products": [{"ticketTypeCode": "2CS", "routeCode": "00720"}]},
    {"id": "bundle_4","products": [{"ticketTypeCode": "2DS", "routeCode": "00720"}]},
...
]

The availability response will indicate whether each individual product is available, or not, at the time of asking. However, it doesn't provide any information about whether two or more of these products are available at the same time. For example, with this type of search the response may indicate that both the SVS and SDS are available. However, what it doesn't confirm is that these products are both available at the same time. It may be that their respective availabilities both ultimately depend on the same seat, so if one is booked the other cannot be booked, and vice versa.

This type of request is ok when the querying system is trying to identify which products a single passenger may be able to book. It should not be used to infer any availability beyond that single passenger.

Multiple Product Bundles: Relative availability

The Basic Usage and Mono Product Bundles both take the approach of determining availability for products in isolation from each other. This has its place but it is often more useful to understand the availability of products in relation to each other. To do this consumers can specify multiple products in a single bundle, and when doing so their availability will be considered in conjunction with other products in that bundle. This has particular power in multi-passenger bookings (see below) but for the single passenger scenario a good example of where this can be used is when a passenger is looking to book both a bike and a seat. For this example the Mono Product Bundle example can be extended as follows:

"bundles": [
     {"id": "bundle_1","products": [
          {"ticketTypeCode": "SVS", "routeCode": "00000"}, {"ticketTypeCode": "BIK", "routeCode": "00000"}]},
     {"id": "bundle_2","products": [
          {"ticketTypeCode": "SDS", "routeCode": "00000"}, {"ticketTypeCode": "BIK", "routeCode": "00000"}]},
     {"id": "bundle_3","products": [
          {"ticketTypeCode": "2CS", "routeCode": "00000"}, {"ticketTypeCode": "BIK", "routeCode": "00000"}]},
     {"id": "bundle_4","products": [
          {"ticketTypeCode": "2DS", "routeCode": "00000"}, {"ticketTypeCode": "BIK", "routeCode": "00000"}]},
     ...
]

which for each bundle is asking the question whether the specified product AND a bike reservation are both available at the same time. If the answer is yes then the bundle outcome in the response for the respective bundle would be FULL_AVAILABILITY. If the answer is no (i.e. one or both the specified product and/or bike is not available) then the bundle outcome for that bundle will be NO_AVAILABILITY.

Multiple Product Bundles: Sequencing

The above example demonstrated how a bundle can be used to determine relative availability of 2 products, checking for when products A AND B are both available. But there is an alternative method of relative availability which is checking whether product A OR product B is available. This can be achieved using the Mono Product Bundle approach to ask for every products availability individually and then looking at the results. But this involves sending and receiving a long list of bundles, which is relatively inefficient and slow. The availability API offers the option of answering this 'OR' question with one bundle, by using priority 'sequencing'.

When constructing a bundle the consumer can choose to include a sequence number with each product. It is entirely up to the consumer how they choose a priority sequence, but an obvious example is by price; with the cheapest product in a range having the lowest sequence number and the most expensive the highest.

"bundles": [
     {"id": "bundle_1", "products": [
          {"ticketTypeCode": "W2A","routeCode": "00820", "sequenceNumber": 1},
          {"ticketTypeCode": "W2B","routeCode": "00820", "sequenceNumber": 2},
          {"ticketTypeCode": "W2C","routeCode": "00820", "sequenceNumber": 3},
          {"ticketTypeCode": "W2D","routeCode": "00820", "sequenceNumber": 4},
          ...
          {"ticketTypeCode": "W2Z","routeCode": "00820", "sequenceNumber": 26}
     ]}
]

The above example assumes a range of standard class advance products, with the cheapest priced as "W2A" and the most expensive priced as "W2Z". By specifying this range of products (which only differ by price) with a sequence the availability response will return only one product in the response, which will be the product with the lowest sequence number that is available.

"bundles": [{
     "bundleOutcome": "FULL_AVAILABILITY",
     "id": "bundle_1",
     "products": [{
          "routeCode": "00820",
          "ticketTypeCode": "W2F",
          "items": [{
               "tariffCode": "500-W2F-S01",
               "inventoryClass": "2S",
               "legId": "segment_1",
               "passengerIds": ["passenger_1"]
          }]
     }]
}]

Without sequencing the response would contain a bundle outcome for all 26 products in the request, with some showing as NO_AVAILABILITY and others as FULL_AVAILABILITY and the consumer would have to process all of these results to determine what to show to a Customer. By using sequencing this is handled for them and the result is much smaller and quicker to process.

Multi-Passenger Requests

The examples above all assume a single passenger. However, it is common to want to know availability for multiple passengers who are travelling together. The availability API allows users to specify multiple passengers within the passenger array:

"passengers": [
      {"id": "passenger_1", "statusCode": "000"},
      {"id": "passenger_2", "statusCode": "000"}
]

NOTE: It is important that requests are made with the _correct _number of passengers. The new reservations service has a completely new approach regarding excess capacity (see below) and supplying requests with more passengers than required is not a valid way to determine this.

Within each product in a bundle you can either:

• not include a passengerIds array, in which case the products will be checked for all passengers; OR
• include a passengerIds array, in which case the products will only be checked for the specified passengers

If we assume 2 passengers have been included in the passenger array as illustrated above then the following:

"bundles": [{"id": "bundle_1","products": [{"ticketTypeCode": "SVS", "routeCode": "00000"}]}]

Results in availability being checked for both passengers. By specifying one or more passengersIds with the product object it is possible to limit the check to just those passengers. For example:

"bundles": [{"id": "bundle_1","products": [{"ticketTypeCode": "SVS", "routeCode": "00000", "passengerIds": ["passenger_1"]}]}]

Results in the availability being checked for the specified passenger only.

As seen above in Multiple Product Bundles: Relative availability, it is possible to specify multiple products within a bundle. This becomes more powerful when multiple passengers are introduced into the equation as it becomes possible to check the availability of different passenger/product combinations. For example:

"bundles": [{"id": "bundle_1","products": [
    {"ticketTypeCode": "SVS", "routeCode": "00000", "passengerIds": ["passenger_1"]},
    {"ticketTypeCode": "S0S", "routeCode": "00000", "passengerIds": ["passenger_2"]}
]}]

Checks for the concurrent availability of the SVS product for passenger 1 and the SOS product for passenger 2.

To check if both products are available for both passengers would need a Mono Product Bundles style request:

"bundles": [
    {"id": "bundle_1","products": [{"ticketTypeCode": "SVS", "routeCode": "00000"}]},
    {"id": "bundle_2","products": [{"ticketTypeCode": "SOS", "routeCode": "00000"}]}
]

In this case there is no need to specify passengerIds as this is done by default.

To determine the best option between two products (e.g. assuming SVS is cheaper than SOS) then as shown above sequencing can be added to the bundle, for example:

"bundles": [{"id": "bundle_1","products": [
    {"ticketTypeCode": "SVS", "routeCode": "00000", "sequenceNumber": 1},
    {"ticketTypeCode": "S0S", "routeCode": "00000", "sequenceNumber": 2}
]}]

which in this case would return the SVS product with a bundle outcome of FULL_AVAILABILITY if it is available for both passengers. If the SVS isn't available for both passengers but the SOS product is then the SOS product would be returned with the FULL_AVAILABILITY bundle outcome. And if neither product was available for both passengers you would get the following returned:

"bundles": [{
    "bundle_outcome": "NO_TARIFF",
    "ref_id": "bundle_1"
}]

Excess Capacity

One of the common practices with the Retail SOPI was to request more passengers than needed in availability requests to get a view on what excess capacity may be available for a given product (up to a user's configured limit, usually 9). As mentioned above, if a similar approach was taken with the new interface then incorrect or misleading information would be returned in terms of product availability. Instead a new feature has been added to bundle responses to automatically communicate excess capacity.

If we look again at two passengers, a request may be submitted with:

"passengers": [{"id": "passenger_1", "statusCode": "000"},{"id": "passenger_2", "statusCode": "000"}]
...
"bundles": [{"id": "bundle_1","products": [{"ticketTypeCode": "SVS", "routeCode": "00000"}]}]

which may generate a response like:

"bundles": [{
      "bundleOutcome": "FULL_AVAILABILITY",
      "id": "bundle_1",
      "products": [{
           "routeCode": "00000",
           "ticketTypeCode": "SVS",
           "items": [{
                "tariffCode": "500-SVS-S01",
                "inventoryClass": "2S",
                "legId": "segment_1",
                "passengerIds": ["passenger_1", "passenger_2"],
                "cappedAvailability": 5
           }]
      }]
}]

Note that with this example a cappedAvailability value has been added to the response. This capped availability tells the consumer that there is a total of 5 of these products currently available for this type of passenger on this service, including the two requested. From this it is possible to determine the excess capacity is 3.

If a cappedAvailability value is not returned then the number of available products is in excess of the maximum number the consumer is permitted to know (usually 9). So a FULL_AVAILABILITY bundle outcome with no cappedAvailability value means that there are 9 or more of these products currently available on this service to this type of passenger.

Bundle Outcome

The below table provides a description of what each Bundle Outcome means:

Last update: 02-Aug-2024 15.09: ASSIST API Documentation Maintenance: 'reservations-eapi', Version 'v2', Page 'Availability - Bundle Concepts', Revision 'A'.

To request updates to this text please contact Neil Barkham.